<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Decomposing ECLiPSe terms in C
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot074.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot073.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot076.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc140">C.2</A>&nbsp;&nbsp;Decomposing ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> terms in C</H2>
The following group of functions type-check an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> term and
retrieve its contents if it is of the correct type.
The return code is PSUCCEED for successful conversion.
If a variable was encountered instead INSTANTIATION_FAULT is returned.
Other unexpected types yield a TYPE_ERROR. Special cases are explained below.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"><B>int		ec_get_string(const pword,char**)</B><DD CLASS="dd-description"><BR>
	checks whether the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> pword is a string (or atom) and converts
	it to a C string. This string is volatile, ie. it should be copied
	when it is required to survive resuming of ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_get_string_length(const pword,char**,long*)</B><DD CLASS="dd-description"><BR>
	the same as ec_get_string(), but returns also the string's length.
	Note that ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> strings may contain null characters!<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_get_atom(const pword,dident*)</B><DD CLASS="dd-description"><BR>
	checks whether the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> pword is an atom, and if so,
	return its dictionary identifier.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_get_long(const pword,long*)</B><DD CLASS="dd-description"><BR>
	checks whether the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> pword is a word-sized integer,
	and if so, returns it as a C long.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_get_double(const pword,double*)</B><DD CLASS="dd-description"><BR>
	checks whether the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> pword is a floating point number,
	and if so, returns it as an C double.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_get_nil(const pword)</B><DD CLASS="dd-description"><BR>
	checks whether the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> pword is nil, the empty list.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_get_list(const pword,pword*,pword*)</B><DD CLASS="dd-description"><BR>
	checks whether the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> pword is a list, and if so,
	returns its head and tail. If it is nil, the return code is PFAIL.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_get_functor(pword,dident*)</B><DD CLASS="dd-description"><BR>
	checks whether the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> pword is a structure, and if so,
	returns the functor.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_get_arg(const int n,pword,pword*)</B><DD CLASS="dd-description"><BR>
	checks whether the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> pword is a structure, and if so,
	returns the n'th argument. The return code is RANGE_ERROR
	if the argument index is out of range.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_arity(pword)</B><DD CLASS="dd-description"><BR>
	returns the arity (number of arguments) of an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> pword
	if it is a structure, otherwise zero.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_get_handle(const pword,const t_ext_type*,t_ext_ptr*)</B><DD CLASS="dd-description"><BR>
	checks whether the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> pword is a handle whose method table
	matches the given one, and if so, the data pointer is returned.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_is_var(const pword)</B><DD CLASS="dd-description"><BR>
	checks whether the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> pword is a variable.
	Note that the return values are PSUCCEED are PFAIL
	rather than standard C truth values.</DL>
<HR>
<A HREF="embroot074.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot073.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot076.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
